Skip to main content
POST
Search memories [OSS + Cloud]

Authorizations

Authorization
string
header
required

API key issued by EverOS, sent as Authorization: Bearer <api_key>.

Body

application/json
query
string
required

The natural-language query to retrieve against.

Minimum string length: 1
app_id
string
default:default

Scope to search in, defaulting to "default". Must match the pair used on write.

project_id
string
default:default

Second half of the scope, defaulting to "default".

user_id
string | null

Search one user's memories — matched against the messages' sender_id. Exactly one of user_id / agent_id is required.

Minimum string length: 1
agent_id
string | null

Search one agent's memories (cases and skills). Exactly one of user_id / agent_id is required.

Minimum string length: 1
method
enum<string>
default:hybrid

Retrieval strategy. "keyword" is lexical, "vector" is embedding similarity, "hybrid" (default) combines both, and "agentic" lets the engine run a multi-round LLM-guided retrieval — more thorough, slower.

Available options:
keyword,
vector,
hybrid,
agentic
top_k
integer
default:-1

Maximum number of hits. Either -1 (the default, letting the engine decide) or a value from 1 to 100; anything else is rejected with 422.

radius
number | null

Vector-similarity radius, 0.0–1.0. Unset leaves it to the engine.

Required range: 0 <= x <= 1
min_score
number | null

Post-fusion score floor, 0.0–1.0. Applies to the episode hybrid (hierarchy) path only; other paths ignore it. The hybrid path fuses its two routes into a probability, so unlike a raw keyword or vector score this floor is an absolute bar and 0.0–1.0 is the real range.

Required range: 0 <= x <= 1
include_profile
boolean
default:false

Also return the user's profile alongside the hits, saving a second call. Ignored for an agent owner, whose results carry no profiles.

with_readable_episode
boolean
default:false

Attach a human-readable rendering of each episode to the returned items, for display only — it is not indexed, filterable or scored, and callers fall back to episode when it is null. Ignored for an agent owner.

enable_llm_rerank
boolean
default:false

Opt-in LLM rerank, and only for hybrid agent_case / agent_skill retrieval. The episode hybrid path has its own fact eviction and ignores this, as do keyword, vector and agentic.

filters
FilterNode · object | null

Optional filter tree — recursive AND / OR arrays mixed with the scalar conditions being matched.

Response

Successful Response

request_id
string
required

Request trace id (peer to data)

data
SearchData · object
required

Endpoint-defined business result